Migrate PHP SDK codegen to use blueprint as sole input by razor-x · Pull Request #448 · seamapi/php

razor-x · 2026-07-22T14:56:08Z

This PR migrates the PHP SDK code generator to use the @seamapi/blueprint as the sole input source, eliminating the dependency on OpenAPI schema parsing and temporary workaround code.

Summary

The codegen pipeline has been refactored to derive all PHP SDK source files directly from the blueprint, removing the intermediate OpenAPI parsing layer that was previously used for output parity with the legacy generator.

Key Changes

Removed OpenAPI parsing layer: Deleted temporary OpenAPI utility files (deep-extract-resource-object-schemas.ts, get-parameter-and-response-schema.ts, deep-flatten-one-of-and-all-of-schema.ts, flatten-obj-schema.ts, types.ts, map-parent-to-children-resource.ts, get-filtered-routes.ts, endpoint-rules.ts) that were frozen workarounds for output parity
Added blueprint-based resource modeling: Introduced resource-model.ts to build resource object class models directly from blueprint resources, handling nested objects, lists, and discriminated unions
Updated codegen entry point: Modified routes.ts to use blueprint as the only input, removing all OpenAPI schema consultation
Simplified type mapping: Updated map-php-type.ts and class-model.ts to work with blueprint types instead of OpenAPI schemas
Updated layout builders: Modified object.ts and seam-client.ts to use blueprint-derived resource models
Generated output changes:
- All object properties now default to nullable (?? null) since blueprint doesn't track required properties
- Removed unused object classes (Pagination, PhoneRegistration)
- Added new action attempt-related object classes for better type coverage
- Updated all from_json methods to use null coalescing for consistency

Implementation Details

The resource object model now directly maps blueprint resources to PHP classes, with nested properties and discriminated unions properly flattened into single classes with the union of variant properties. This eliminates the need for complex OpenAPI schema traversal and normalization logic.

https://claude.ai/code/session_01EjeywMUAsXPYML3H7imc4H

Remove all the temporary output-parity workarounds and their TODOs from the codegen. The generator no longer parses the OpenAPI spec: resource object classes, client classes, and methods are all derived from @seamapi/blueprint. Events, action attempts, and discriminated object lists are merged into single classes; nested namespaces are now wired to their parent clients; the parameter sort precedence bug is fixed; and integer parameters map to float instead of mixed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EjeywMUAsXPYML3H7imc4H

Filter blueprint resources, events, action attempts, and their properties on isUndocumented, dropping resource object classes such as PhoneSession and BridgeClientSession that are not part of the public SDK. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EjeywMUAsXPYML3H7imc4H

Upgrade @seamapi/blueprint to 0.57.0 and map integer request parameters to the PHP int type instead of float. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EjeywMUAsXPYML3H7imc4H

razor-x · 2026-07-22T15:29:10Z

BREAKING CHANGE: The parameter order of two get methods changed so the primary resource ID is now the first parameter. Positional callers must be updated — the old first argument is otherwise silently sent as the wrong parameter:

$seam->events->get(): $event_id is now first (was $device_id).
$seam->acs->users->get(): $acs_user_id is now first (was $acs_system_id).

BREAKING CHANGE: ActionAttempt->result is now a typed ActionAttemptResult|null instead of raw decoded JSON. Typed result fields (e.g. acs_credential_on_encoder) are still available as properties; untyped fields (result->access_code, result->noise_threshold) are no longer present.

BREAKING CHANGE: created_at was removed from AcsCredentialErrors, AcsEntranceErrors, PhoneErrors, PhoneWarnings, and ThermostatScheduleErrors. It was previously injected into every error and warning class by the generator; these five are not defined with it in the API spec.

BREAKING CHANGE: Resource object constructor parameters are now ordered alphabetically and uniformly nullable. Only affects code constructing resource objects positionally; objects returned by the SDK are unaffected.

Non-breaking: undocumented resources (e.g. PhoneSession, BridgeClientSession) and undocumented properties are no longer generated; integer request parameters are now typed ?int instead of mixed; nullable list and object property types were widened; workspaces->update() and the acs->encoders->simulate client were added.

Generated by Claude Code

Upgrade @seamapi/blueprint to 0.58.0, which adds the isInt flag to number properties, and @seamapi/types to 1.966.0, which restores the missing created_at property on error and warning resources. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EjeywMUAsXPYML3H7imc4H

razor-x · 2026-07-22T15:55:43Z

Revised breaking-change note (supersedes my previous comment — after upgrading to @seamapi/types 1.966.0, created_at is present in the spec again, so that item no longer applies):

BREAKING CHANGE: The parameter order of two get methods changed so the primary resource ID is now the first parameter. Positional callers must be updated — the old first argument is otherwise silently sent as the wrong parameter:

$seam->events->get(): $event_id is now first (was $device_id).
$seam->acs->users->get(): $acs_user_id is now first (was $acs_system_id).

BREAKING CHANGE: ActionAttempt->result is now a typed ActionAttemptResult|null instead of raw decoded JSON. Typed result fields (e.g. acs_credential_on_encoder) are still available as properties; untyped fields (result->access_code, result->noise_threshold) are no longer present.

BREAKING CHANGE: Resource object constructor parameters are now ordered alphabetically and uniformly nullable. Only affects code constructing resource objects positionally; objects returned by the SDK are unaffected.

Non-breaking: undocumented resources (e.g. PhoneSession, BridgeClientSession) and undocumented properties are no longer generated; integer parameters and properties are now typed int instead of mixed/float; nullable list and object property types were widened; workspaces->update() and the acs->encoders->simulate client were added.

Generated by Claude Code

Pick up the isItemInt flag on number list parameters and properties. Generated output is unchanged since PHP list types do not declare an item type. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EjeywMUAsXPYML3H7imc4H

claude added 3 commits July 22, 2026 14:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Migrate PHP SDK codegen to use blueprint as sole input#448

Migrate PHP SDK codegen to use blueprint as sole input#448
razor-x wants to merge 5 commits into
mainfrom
claude/codegen-cleanup-blueprint-ir2sm8

razor-x commented Jul 22, 2026

Uh oh!

razor-x commented Jul 22, 2026

Uh oh!

razor-x commented Jul 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

razor-x commented Jul 22, 2026

Summary

Key Changes

Implementation Details

Uh oh!

razor-x commented Jul 22, 2026

Uh oh!

razor-x commented Jul 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants